{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "name": "NeuromatchAcademy_Neuromatch_Tutorial_Format",
      "provenance": [],
      "collapsed_sections": [],
      "toc_visible": true,
      "include_colab_link": true
    },
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.7.3"
    },
    "toc-autonumbering": true
  },
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "view-in-github",
        "colab_type": "text"
      },
      "source": [
        "<a href=\"https://colab.research.google.com/github/NeuromatchAcademy/course-content/blob/style_guide/organization/Neuromatch_Tutorial_Format.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "fDXAYdIHuyCV"
      },
      "source": [
        "\n",
        "# Neuromatch Academy: Week ?, Day ?, Tutorial ?\n",
        "# Name of Day: Name of Tutorial\n",
        "\n",
        "__Content creators:__ Name Surname, Name Surname\n",
        "\n",
        "\n",
        "\n",
        "__Content reviewers:__ Name Surname, Name Surname. \n",
        "\n",
        "__Content editors:__ Name Surname, Name Surname.\n",
        "\n",
        "__Production editors:__ Name Surname, Name Surname.  "
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "gzAa0I1xZ79h"
      },
      "source": [
        "---\n",
        "#Tutorial Objectives\n",
        "\n",
        "Use a line (---) separator from title block to objectives. You should briefly introduce your content here in a few sentences. In this tutorial, you will learn what an NMA tutorial notebook should look like. \n",
        "\n",
        "Then have a few specific objectives for this tutorial, ideally [SMART goals](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5944406/#:~:text=1%20The%20mnemonic%20SMART%E2%80%94Specific,a%20well%2Dwritten%20learning%20objective.&text=Verbs%20such%20as%20understand%2C%20know,measurable%20and%20should%20be%20avoided.). By the end of this tutorial you will be able to:\n",
        "*   Understand the format of an NMA tutorial\n",
        "*   Make code exercises, interactive demos, and group discussions the correct structure\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "wlndBdbV5iJF",
        "cellView": "form"
      },
      "source": [
        "#@markdown Tutorial slides\n",
        "# you should link the slides for all tutorial videos here (we will store pdfs on osf)\n",
        "\n",
        "from IPython.display import HTML\n",
        "HTML('<iframe src=\"https://mfr.ca-1.osf.io/render?url=https://osf.io/kaq2x/?direct%26mode=render%26action=download%26mode=render\" frameborder=\"0\" width=\"960\" height=\"569\" allowfullscreen=\"true\" mozallowfullscreen=\"true\" webkitallowfullscreen=\"true\"></iframe>')"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "V0iDJGBMzbMQ"
      },
      "source": [
        "---\n",
        "# Setup"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "zDsBmvTSjFeu"
      },
      "source": [
        "In this section, we have:\n",
        "\n",
        "\n",
        "1.  **Import cell**: imports all libraries you use in the tutorial\n",
        "2.  **Hidden Figure settings cell**: sets up the plotting style (copy exactly)\n",
        "3. **Hidden Plotting functions cell**: contains all functions used to create plots throughout the tutorial (so students don't waste time looking at boilerplate matplotlib but can here if they wish to). Please use only matplotlib for plotting for consistency.\n",
        "4. **Hidden Helper functions cell**: This should contain functions that students have previously used or that are very simple. Any helper functions that are being used for the first time and are important should be placed directly above the relevant text or exercise (see Section 1.1 for an example)\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "cellView": "both",
        "id": "3Yuh005kCT0v"
      },
      "source": [
        "# Imports\n",
        "\n",
        "# Import only the libraries/objects that you use in this tutorial. \n",
        "\n",
        "# If any external library has to be installed, !pip install library --quiet\n",
        "# follow this order: numpy>matplotlib. \n",
        "# import widgets in hidden Figure settings cell\n",
        "\n",
        "import numpy as np\n",
        "import matplotlib.pyplot as plt"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "PCOz4jKJXGya",
        "cellView": "form"
      },
      "source": [
        "#@title Figure settings\n",
        "import ipywidgets as widgets       # interactive display\n",
        "%config InlineBackend.figure_format = 'retina'\n",
        "plt.style.use(\"https://raw.githubusercontent.com/NeuromatchAcademy/course-content/master/nma.mplstyle\")"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "cellView": "form",
        "id": "EojkgkRwizCs"
      },
      "source": [
        "#@title Plotting functions\n",
        "\n",
        "# You may have functions that plot results that aren't \n",
        "# particularly interesting. You can add these here to hide them. \n",
        "\n",
        "def plotting_z(z):\n",
        "  \"\"\"This function multiplies every element in an array by a provided value\n",
        "\n",
        "  Args:\n",
        "    z (ndarray): neural activity over time, shape (T, ) where T is number of timesteps\n",
        "  \n",
        "   \"\"\"\n",
        "\n",
        "  fig, ax = plt.subplots()\n",
        "\n",
        "  ax.plot(z)\n",
        "  ax.set(\n",
        "       xlabel='Time (s)',\n",
        "       ylabel='Z',\n",
        "       title='Neural activity over time'\n",
        "      \n",
        "   )\n"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "vGVC4AWz41jD",
        "cellView": "form"
      },
      "source": [
        "#@title Helper functions\n",
        "\n",
        "# If any helper functions you want to hide for clarity (that has been seen before\n",
        "# or is simple/uniformative), add here\n",
        "# If helper code depends on libraries that aren't used elsewhere,\n",
        "# import those libaries here, rather than in the main import cell\n",
        "\n",
        "\n",
        "\n"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "nULavCfq4o07"
      },
      "source": [
        "---\n",
        "\n",
        "# Section 1: Example of tutorial structure\n",
        "\n",
        "The above section header should be a description of what the section covers"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "cellView": "form",
        "id": "ThcPwgvzvV-6"
      },
      "source": [
        "#@title Video 1: Video 1 Name\n",
        "# Insert the ID of the corresponding youtube video\n",
        "from IPython.display import YouTubeVideo\n",
        "video = YouTubeVideo(id=\"\", width=854, height=480, fs=1)\n",
        "print(\"Video available at https://youtu.be/\" + video.id)\n",
        "video\n"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "z8axuI6upLv4"
      },
      "source": [
        "Text about the first concept. Don't make too long to reduce reading times during tutorial (extra text for later reference can go in appendix). Instead of long paragraphs, use bullet points of multiple shorter paragraphs. In both the videos and text, you should not \"speak in variables.\" For example, don't say \"change alpha\", say \"change the learning rate\" or \"change the learning rate, alpha\""
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "j9n17gXFOIXX"
      },
      "source": [
        "## Section 1.1:  Different types of activities in an NMA tutorial (subsection header)\n",
        "\n",
        "You can have students complete coding exercises, play with interactive demos, or have group discussions."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "ZosC4SmFQnhq"
      },
      "source": [
        "### Coding Exercise 1.1: Helpful exercise name (ex. fitting a linear regression model)\n",
        "\n",
        "This exercise fits in this subsection so is a level 3 header. We name it after the section it is in.\n",
        "\n",
        "Very briefly summarize the exercise here. The first exercise should not be too difficult, to serve as a warm-up for students. Outputs of the code cell will ideally be a plot (so students can easily check against the correct one). In limited cases, the output may be printing numbers, text, etc. In that case you need to write the solution output manually after the exercise (E.g.: \"You should see [4, 5, 6] when running the cell above\").\n",
        "\n",
        "\n",
        "Warn them when they will use a helper function. For example: In this exercise, you will also invoke `multiply_array` which multiplies an array by a scalar (a silly example).\n",
        "\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "cellView": "form",
        "id": "z7_QQyrXs3lV"
      },
      "source": [
        "# @markdown *Execute this cell to enable the array multiplication function: `multiply_array`*\n",
        "\n",
        "\n",
        "def multiply_array(x, c):\n",
        "  \"\"\"Multiply every element in an array by a provided value\n",
        "\n",
        "  Args:\n",
        "    x (ndarray): An array of shape (N,) \n",
        "    c (scalar): multiplicative factor\n",
        "\n",
        "  Returns:\n",
        "    ndarray: output of the multiplication \n",
        "  \"\"\"\n",
        "\n",
        "  y = x * c\n",
        "\n",
        "  return y"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "bWDbayoJwtIs"
      },
      "source": [
        "__Editor guideline:__ the above structure allows us to make the notebooks cleaner by hiding functions but still keep relevant functions close to where students will encounter them. Make sure to have the function in the markdown text so it's searchable."
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "0dYxSDmqQgAC"
      },
      "source": [
        "def generic_function(x):\n",
        "  \"\"\"Google style doc string. Brief summary of what function does here\n",
        "  \n",
        "  Args:\n",
        "    x (ndarray): An array of shape (N,) that contains blah blah\n",
        "\n",
        "  Returns:\n",
        "    ndarray: The output is blah blah\n",
        "  \"\"\"\n",
        "  #################################################\n",
        "  ## TODO for students: details of what they should do ##\n",
        "  # Fill out function and remove\n",
        "  raise NotImplementedError(\"Student exercise: say what they should have done\")\n",
        "  #################################################\n",
        "  \n",
        "  # Have a comment for every line of code they need to write, and when possible have\n",
        "  # variables written with ellipses where they should fill in or ellipses where they should\n",
        "  # fill in inputs to functions\n",
        "  y = multiply_array(..., 5)\n",
        "\n",
        "  # Another comment because they need to add another line of code\n",
        "  z = ...\n",
        "\n",
        "  return z\n",
        "\n",
        "x = np.array([4, 5, 6])\n",
        "z = generic_function(x)\n",
        "\n",
        "# we usually define the plotting function in the hidden Helper Functions\n",
        "# so students don't have to see a bunch of boilerplate matplotlib code\n",
        "plotting_z(z)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "vd9JfcDrbQ_d"
      },
      "source": [
        "---\n",
        "__Editor guideline for exercise solution formatting:__\n",
        "- the presence of # to_remove solution in the first line of solution block\n",
        "- The absence of the fenced (#####) block that raises a NotImplementedError\n",
        "- Valid code replacing all ellipses  (...)\n",
        "- Code that uses or depends on the completed function/lines is uncommented\n",
        "- Plotting code is indented under a with plt.xkcd(): context manager.\n",
        "- **All other comments and code should be identical**\n",
        "---"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "cellView": "both",
        "id": "tycSi5Pxbsne"
      },
      "source": [
        "# to_remove solution\n",
        "def generic_function(x):\n",
        "  \"\"\"Google style doc string. Brief summary of what function does here\n",
        "  \n",
        "  Args:\n",
        "    x (ndarray): An array of shape (N,) that contains blah blah\n",
        "\n",
        "  Returns:\n",
        "    ndarray: The output is blah blah\n",
        "  \"\"\"\n",
        "\n",
        "  # Have a comment for every line of code they need to write, and when possible have\n",
        "  # variables written with ellipses where they should fill in or ellipses where they should\n",
        "  # fill in inputs to functions\n",
        "  y = multiply_array(x, 5)\n",
        "\n",
        "  # Another comment because they need to add another line of code\n",
        "  z = y + 6\n",
        "\n",
        "  return z\n",
        "\n",
        "x = np.array([4, 5, 6])\n",
        "z = generic_function(x)\n",
        "\n",
        "# we usually define the plotting function in the hidden Helper Functions\n",
        "# so students don't have to see a bunch of boilerplate matplotlib code\n",
        "# xkcd style for solution plot\n",
        "with plt.xkcd():  \n",
        "  plotting_z(z)"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "UhDupvg6W4f7"
      },
      "source": [
        "### Interactive Demo 1.1: Name of demo\n",
        "\n",
        "Here, we will demonstrate how to create a widget if you would like to use a widget to demonstrate something. Make sure the use a @title cell and hide the contents by default, because the code to make the widget is often pretty ugly and not important for the students to see. \n",
        "\n",
        "If the widget makes use of a function that must be completed as part of an exercise, you may want to re-implement the correct version of the function inside the widget cell, so that it is useful for a student who got completely stuck.\n",
        "\n",
        "There should be specific questions asked about the demo (e.g. what happens when you do this?)"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "976PhJZaXDP5",
        "cellView": "form"
      },
      "source": [
        "#@markdown Make sure you execute this cell to enable the widget!\n",
        "\n",
        "x = np.arange(-10, 11, 0.1)\n",
        "\n",
        "def gaussian(x, mu, sigma):\n",
        "  px = np.exp(-1 / 2 / sigma**2 * (mu - x) ** 2)\n",
        "  px = px / px.sum()\n",
        "  return px\n",
        "\n",
        "@widgets.interact\n",
        "def plot_gaussian(mean=(-10, 10, .5), std=(.5, 10, .5)):\n",
        "  plt.plot(x, gaussian(x, mean, std))\n"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "O0-u0qhNgATu"
      },
      "source": [
        "# to_remove explanation\n",
        "\n",
        "\"\"\"\n",
        "Discussion: Write a dicussion about/answers to any open-ended questions you pose (either about a demo or elsewhere)\n",
        "\n",
        "You can write a paragraph or two of nice didactic text\n",
        "within a single comment. \n",
        "\"\"\";"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "f4h1Y-BxcQyp"
      },
      "source": [
        "__Editor guideline:__ note that the form header for the cell above is __to_remove explanation__, not __to_remove solution__."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "CrTpOZZDW9qZ"
      },
      "source": [
        "maybe some more text about what exercises showed (if helpful). \n",
        "The Gaussian is: \n",
        "- bumpy in the middle\n",
        "- symmetric\n",
        "- almighty"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "-cXAncan4Xqk"
      },
      "source": [
        "### Think! 1.1: Name of discussion topic\n",
        "\n",
        "In addition to code exercises and interactive demos, you can have \"discussion exercises\" where students discuss open-ended questions. Each should roughly replace a code exercise so take about 10 minutes.\n",
        "\n",
        "E.x. What do you think contributes to a good learning experience? Take 2 minutes to think in silence, then discuss as a group (~10 minutes).\n",
        "\n",
        "DEEP LEARNING ONLY (not for comp neuro): You can then include an airtable form through which students can write down their thoughts. This helps us to see how students are thinking (as we can read the responses). You should also still include the explanation cell with the answer or some discussion to aid students.\n",
        "\n",
        "\n",
        "\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "RWWAsjjpqVTW"
      },
      "source": [
        "# airtable\n",
        "# relevant_variable_name: text "
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "2jMFzfUSqX1N"
      },
      "source": [
        "__Editor guideline:__ note that to notify us where you'd like an airtable input form, use this special syntax. The first line is \"# \n",
        "\n",
        "*   First line is `# airtable`\n",
        "*   Relevant variable name on the second line should be something related to the question you're asking (an identifier). For example it could be \"learning_experience_contribs\" in this example. It should be a valid Python variable (no spaces, don't start with numbers).\n",
        "*   You can have different types of inputs: text, numerical, or multiple choice.\n",
        "    * If you want a text answer, use `# relevant_variable_name: text`\n",
        "    * If you want a numerical answer, use `# relevant_variable_name: number`\n",
        "    * If you want a multiple choice answer, use `# relevant_variable_name: [option1, option2, option3]` where you fill out what the options are. For example, `# network_arch: [MLP, CNN, RNN, Transformer]`\n"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "id": "YTCPwDk7os4i"
      },
      "source": [
        "# to_remove explanation\n",
        "\n",
        "\"\"\"\n",
        "Discussion: Write a dicussion about/answers to any open-ended questions you pose (either about a demo or elsewhere)\n",
        "\n",
        "You can write a paragraph or two of nice didactic text\n",
        "within a single comment. \n",
        "\"\"\";"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "MFaYDWZQ4TEF"
      },
      "source": [
        "## Section 1.2: Name"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "rHCBusgk74Mx"
      },
      "source": [
        "### Coding Exercise 1.2: Name\n",
        "\n",
        "This exercise is in a subsection so has a level 3 header"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "EuqpiL2Av-vd"
      },
      "source": [
        "---\n",
        "# Section 2: Notation Standards\n",
        "\n",
        "For the comp neuro course, our math notation standards so far are located [here](https://docs.google.com/spreadsheets/d/11YXS39tIQb_x-wLNbbGBu1uQ9Dl4drBqUQbKpw0BQbc/edit?pli=1#gid=1974724555) (accessible from a neuromatch account). This is a work in progress so check back later. \n",
        "\n",
        "For the deep learning course, we will be using [this notation](https://www.deeplearningbook.org/contents/notation.html). You can find and use the latex [here](https://github.com/goodfeli/dlbook_notation/blob/master/notation.tex)."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "sGr5NQmk151W"
      },
      "source": [
        "---\n",
        "# Section 3: An additional example section\n",
        "\n",
        "Separate with lines and add more content here! Depending on how the videos were created, you may or may not have a separate video for each section"
      ]
    },
    {
      "cell_type": "code",
      "metadata": {
        "cellView": "form",
        "id": "AFd7Ji-twKIK"
      },
      "source": [
        "#@title Video 2: Video 2 Name\n",
        "# Insert the ID of the corresponding youtube video\n",
        "from IPython.display import YouTubeVideo\n",
        "video = YouTubeVideo(id=\"\", width=854, height=480, fs=1)\n",
        "print(\"Video available at https://youtu.be/\" + video.id)\n",
        "video"
      ],
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "qqA6Ajwk1cZ6"
      },
      "source": [
        "## Coding Exercise 3: Name\n",
        "\n",
        "This exercise is in this section (not in a subsection) so has a level 2 header"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "_Z6vKsN89rN1"
      },
      "source": [
        "---\n",
        "# Summary\n",
        "\n",
        "Have a summary of what they learned with specific points.\n",
        "\n",
        "* Specific point A\n",
        "\n",
        "* Specific point B\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Y6Pux46LWw7e"
      },
      "source": [
        "---\n",
        "# Bonus: Name of Bonus section\n",
        "\n",
        "Add extra text that you want students to have for reference later but that will make reading times too long during tutorials. You can have multiple Bonus sections if you'd like, just number them as Bonus 1: Name, Bonus 2: Name, etc. \n",
        "\n",
        "You should not have bonus content interleaved into the tutorial."
      ]
    }
  ]
}